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THE MENUS 


The Apple Menu 


The first item on this menu is "About MacLab." This tells what version of 
MacLab you are working with. 


MacLab is fully compatible with all Desk Accessories that it has been tried on. If 
you find a DA that makes it crash or behave strangely, and you think MacLab might be 
at fault, please tell me about it and I will see what I can do. 


The File Menu 


The first three items, New, Load and Save Experiment do just that: "New" creates 
a new experiment, "Load" gets an experiment from the disk and lets you edit it, and 
"Save" saves the current experiment (always asking you with what file name it should 
be saved). 


"Run Experiment" asks for three things: a) a file which contains the experiment 
which you would like to run, b) an output file in which to store the subject's responses, 
and c) a trial order file which contains a specific order in which to run the trials in the 
experiment. The last two items, the subject output file and the trial order file, are 
optional. If there is no subject output file, responses will not be saved; if there is no 
trial order file, the experiment will be run with the trials in the order they exist in the 
experiment file. 


Printing is supported by MacLab in two ways: if you would like to print out an 
experiment or an order trial file, you should load the appropriate file and, while the 
window the file is in is the topmost window, select the menu choice "Print Current." 
For experiment files, this will print the trial lines in bold-face. One should use this 
method of printing these types of files since when they are stored on disk they contain 
extraneous information. 


Other text files, like subject output files, can be printed using the "Print Output 
File" menu choice. This will just take a text file from disk and print it out as is. The 
only embellishments are the name of the file and the page number at the top of every 


page. 


Finally, the "Quit" menu choice allows you to quit MacLab. If there are unsaved 
files, a reminder is put up that you will lose any changes made since the last time you 
saved the files. 


The Edit Menu 


Editing operations are not currently used in MacLab. However, this menu 
becomes active when Desk Accessories are used so that the DA's may use the standard 
text editing operations. 


The Order Menu 


This menu contains the operations necessary to deal with trial order files. These 
are files that contain numbers, indicating the order in which the trials in an experiment 
are to be run. 


"New Order" creates a new window in which these numbers may be entered. You 
can also load an existing trial order file by using the "Load Order" choice. After you 


have made changes to a trial order file, you can save it with the "Save Order" choice. 


The Lines Menu 


This menu contains operations that can be used on the topmost window, be that 
the Experiment Editor window or the Trial Order window. 


If the topmost window is the Experiment Editor window, the first two choices are 
"Add Trial" and "Add Event." "Add Trial" adds a trial after the current trial. The 
current trial is the trial which contains the "current line." "Add Event" adds an event 
right after the current line. One or both of these choices might be disabled if the 
maximum number of lines or the maximum number of trials have been added. 


The next two choices on the menu change depending on whether the current line 
is a trial line or an event line. If the current line is a trial line, the choices are "Modify 
Trial" and "Delete Trial." "Modify Trial" allows you to modify the name of the trial, 
while "Delete Trial" deletes the trial line and all the events belonging to that trial. If the 
current line is an event line, however, the last two choices on this menu are "Modify 
Event" and "Delete Event." "Modify Trial" and "Modify Event" can also be selected by 
double-clicking on the line you wish to modify. 


If the topmost window is the Trial Order window, then the Lines menu only 
contains two choices: "Add Trial No." and "Delete Trial No.." "Add Trial No." allows 
you to enter ordered sequences of numbers, or just a number at a time. "Delete Trial 
No." deletes all currently selected trial numbers (one can select more than one trial 
number by "dragging" the mouse). 


The Miscellaneous Menu 
"Show File" allows you to display a MacPaint file on the screen, just like it would 


be displayed when an experiment containing that file is run. To stop viewing the file, 
click the mouse. 


"Make Script" and "Run Script" deal with script files. Script files allow you to 
run more than one experiment at a time without stopping between experiments to ask 
for the information needed to run the next experiment. "Make Script" asks you for the 
information relevant to making a script, while "Run Script" runs a script file. 


"Set Pic Files' Location" allows you to specify a disk name or an HFS folder. 
The name that you supply will be added to the front of file names when the experiment 
isrun. Thus, if the picture files for a certain experiment are on the disk named 
"Experiment 1" in an HFS folder named "pictures", the location of the files would be 
"Experiment |:pictures:" and this name is added to the front of the picture files' names 
when the experiment is run. If you do not explicitly specify the location of the picture 
files, they will be assumed to be on the same disk and in the same HFS folder as the 
experiment file (MFS folders are not real folders, in that they are not true sub- 
directories in the file system, so if you are running under MFS (the older Mac filing 
system) you need only specify the disk name followed by a colon, if the picture files are 
on a different disk than the experiment file). So, if the experiment file is in the same 
folder as the picture files, you need not specify the picture files' location. 


"Choose Load-Time Display" allows you to choose a picture file which will be 
displayed when the experiment is running but must be temporarily stopped in order to 
load more pictures or save output to disk. If no such file is specified, a blank (white) 
screen will be displayed at such times. 


THE EXPERIMENT EDITOR 


Trials 


An experiment is made up of trials. There is a limit on the number of trials that 
one can have in an experiment. The number of trials that can still be added is 
constantly displayed at the bottom right of the Experiment Editor window. If you need 
more trials than can be put in one file, you would have to break up your experiment into 
blocks and use a script to run the blocks together. 


Each trial consists of a trial line followed by any number of event lines. When 
adding a trial, you are asked to give a name to the trial. This name becomes part of the 
trial line. The entire trial line appears in the subject response file, but only if the name 
is not blank. In the dialog box that asks you for the name of the trial, you have the 
option of copying a group of one or more existing trials instead of adding just one trial. 
Copying trials copies all lines belonging to the trials (.e. the trial line and all of its 
events). The copied trials' trial numbers are changed to reflect their new position. 
Nothing happens to the trials being copied. 


Events 


Events are what trials are made up of. There is no limit on how many events you 
can put in a trial. There is however a limit on the number of total lines that can be put 
in an experiment (lines include the trial lines and the event lines). The number of lines 
that can be added is constantly displayed at the bottom right of the Experiment Editor 
window. If your experiment needs more lines than are available, you will have to break 
up your experiment into blocks and use the scripting facility. 


An event line is made up of three parts: a) a file name, b) a termination condition, 
and c) a list of things to save. The file name can be as long as 30 characters. Any 
excess characters are chopped off. In the dialog window that lets you add or change 
events, you can click in the Minifinder button to get the standard Mac Minifinder and 
look to see what files you have. The Minifinder will only display files MacLab can 
read and display (files in MacPaint format). Selecting a file with the Minifinder will 
enter its name in the "File name" field. 

NOTE: Watch out for spaces at the end of file names! MacLab does not see 
spaces at ends of file names, so if your files end with spaces MacLab will not find 
them! 


Events terminate on one of three conditions: a) time, b) a key press, or c) a mouse 
click. You must click in the circle next to the termination condition you desire. If this 
is to be a timed display, you must enter the duration of the display. This duration must 
be 33 milliseconds and up in increments of about 17 milliseconds (times can be 33, 50, 
67, 83, 100, 117, 133, 150, _). If the time you enter is too small, or falls between two 


values, it will be coerced to the next value up. If the termination condition is a key 
press, you have to enter the legal response keys (if, in a certain event, the subject 
presses a key not in this legal set, MacLab will beep). There is a maximum of 10 keys 
in this set. Legal keys can be any alpha numeric keys that can be generated without 
pressing either the shift, option, or control keys. Keypad keys and the backquote key 
(*) are not registered. The space bar is registered. To indicate that it is in the legal set 
of keys, use a carat (“), not a space. 


For each event, you can save any combination of the following things to the 
subject response file: a) time displayed, b) key pressed, and c) mouse position. You 
must check all the boxes corresponding to things you want to save. In addition, if you 
are Saving anything in an event, the subject response file will also contain the file name 
of the event. 


Other Displayed Info 


To the right of the text of the experiment MacLab displays the name of the file 
that is displayed. The default name for new experiment files is "No Name." Below the 
file name MacLab shows where event picture files will be looked up on disks, and the 
name of a picture file that will be displayed when MacLab needs to temporarily pause 
the experiment and load more pictures. These last two items are discussed in THE 
MENUS section, in the Miscellaneous menu. Finally, at the bottom right of the 
Experiment Editor window is a list of the remaining space in the MacLab environment. 
One can see the number of trials and lines that can still be added, as well as the 
approximate number of bytes of memory available. 


On Using MacLab with HFS 


If you are using HFS you would probably want to put the pictures to be used in an 
experiment in one folder, apart from other files, since there might be a large number of 
these picture files. In this case, you would use the "Set Pic Files' Location" choice in 
the Miscellaneous menu. The location of the files is made up by the exact name of the 
disk, followed by a colon, and the name of the HFS folders, each followed by a colon, 
you would have to open in the Finder in order to get to the picture files. This is not 
strictly a MacLab convention, but a general HFS convention. Thus if the name of the 
disk is "Disk", and the picture files are in the folder "experiment 1", which folder is 
found inside the folder "pictures", you would have to enter the location 
"Disk:pictures:experiment 1:" (do not forget the colons). What MacLab does is take 
this name and prepend it to the name of each file when the file needs to be loaded. 


Moreover, if the folder which all of the picture files have in common is sub- 
divided into more folders (but the pictures needed for one experiment are not all in the 
same folder), you can add the name of the appropiate sub-folder to the beginning of 
each file name in the event lines themselves. Thus, if the folder "experiment 1" has two 
folders in it, "part 1" and "part 2", and the picture "animal" is in the folder "part 1" 


while the picture "rock" is in the folder "part 2", then, on the events that use the picture 
file "animal" you would use the file name "part 1:animal", while for the file "rock" you 
would use the file name "part 2:rock". 


Experiment File Format 


An experiment file is a plain text file (MacLab creates them with Creator = 
MLAB, Type = TEXT). The first thing in it is a number followed by a character 
(MacLab writes out a carriage return (OD hex)). The number is the number of trials in 
the file (call this number t). Then follow t numbers, separated by one character 
(MacLab writes out spaces as separators; however, every 10th number and the last of 
these numbers is followed by a carriage return, not a space). These numbers indicate 
the line numbers of the trial lines 1 to t. Then comes another number, followed by a 
character (MacLab writes out a carriage return). This is the number of bytes that follow 
— this is the actual text of the experiment. This number should be a multiple of 47, 
since there are 47 characters per line. 


There are three kinds of lines: there is the first line, which contains the string "The 
Experiment Begins Here" followed by the proper number of spaces, except for the last 
character which is a carriage return. Trial lines are made up of the string "Trial" 
followed by the trial number, right-justified in the next 4 bytes. Then follow 5 spaces, 
in their turn followed by the name of the trial (maximum of 32 characters). The rest of 
the 47 characters are spaces, except for the last one which is a carriage return. Event 
lines start with the name of the file, left-justified in the first 30 bytes. Then a space, 
followed by an 11 byte termination string. The first character must be either a T, a K, 
or an M (corresponding to time, key, and mouse terminated events). For timed events, 
the number of milliseconds and the word "msecs" (or as much as fits in the remaining 
10 bytes) follow. For key terminated events, the set of legal responses follows (up to 
10 keys). After the termination string there is a space followed by a 3 byte save string. 
The save string tells what should be saved to disk from the current event. A T means 
the time the picture was up, a K means the key pressed, and an M means the mouse 
location at the termination of the event. The line is ended with a carriage return. Thus 
a line is always 47 characters long. 


After the last line of the experiment comes the word "LTD:" followed by a space 
and, in the next 5 bytes, anumber. The number tells the number of characters in the 
file name that follows (the name of the Load-Time Display file). The file name is 
followed by a carriage return. On the next line comes the word "PFL:" followed by a 
space and, in the next 5 bytes, anumber. The number tells the number of characters in 
the path name that follows (the Pic Files' Location). After the path name there is a 
carriage return. If any of these two last items are empty (the number of characters is 0), 
defaults are used. 


And that's it. 


TRIAL ORDERS 


Trial orders allow you to take an experiment and run its trials in any order. In one 
order file one may specify 1500 trial numbers (one trial can be repeated as often as you 
wish). Trial numbers above the highest possible trial number are not allowed. Trial 
number 0 has a special significance: when the experiment is run, if the order specifies 
trial 0 then, if the next trial 0 cannot be reached without loading more files, the 
experiment is run up to where the order specifies trial 0, and then more files are loaded 
in hope that the next trial 0 will be reached. Thus, a trial number of 0 serves as a 
breakpoint where it is more desirable to take a brief pause than between other trials 
(breaks are only taken between trials, unless a trial is too large to be brought into 
memory at once). 


If you choose to add trial order numbers, these numbers are added after the 
currently selected number. You may add single numbers at a time; in this case, when 
you are done adding numbers, click in the "Done" button. You may also add entire 
sequences of numbers at a time. In the dialog window that lets you add numbers, 
pressing the Return key is equivalent to clicking in the "Add" button. This should 
make adding individual numbers much easier. 


To delete trial numbers, select the trial numbers you want to delete (you may 
delete more than one at a time by "dragging" the mouse to select more than one) and 


select "Delete Trial No." from the Lines menu. The first 0 may not be deleted. 


Trial Order File Format 


The trial order files are just plain text files (MacLab creates them with Creator = 
MLAB, Type = TEXT). These start with the sequence of characters "Orders:" followed 
by a space, and by the number of order numbers to follow in the next 5 bytes, less one 
(the first trial order number, always a 0, is a freebie). Then, in each 4 bytes there is a 
number (the first 0, although not included in the total count, must appear nevertheless). 
There are as many numbers as were specified after the word "Orders:." In the file that 
MacLab creates, the number is left justified in its 4 bytes; thus the last byte is never 
used (since trial numbers currently go from 0 to 299). MacLab makes the last byte a 
space, and, every ten numbers, a carriage return (OD hex). This makes the ouput file 
look "nice." 


RUNNING AN EXPERIMENT 


Starting Up the Experiment 


When you run an experiment, you are asked for three files: the file that the 
experiment is in, an output file to which MacLab should save the subject's responses, 
and a trial order file that specifies in which order to run the trials of the experiment. If 
you do not want the subject's responses to be saved, then click on Cancel when asked 
for an output file. If you want to run the trials in the order in which they are in the 
experiment, and do not have a special trial order file, click in the Cancel button when 
asked for a trial order file. 


Things To Do During the Experiment 


There are two special commands that you can use while MacLab is in the middle 
of an event that is to be terminated by a keystroke: you can stop the experiment, or you 
can go back, instead of to the next event. To stop the experiment, press the mouse 
button and, while holding it down, press the Option key. This will halt the experiment 
in an orderly fashion. 


To go back instead of forwards, hold the mouse button down and press the 
Backspace key. There are limitations to this command. You can only go back to the 
last time that the experiment was stopped for loading. When going back, MacLab goes 
to the previous event that was terminated by a key. If no such events exist after the last 
load, MacLab goes to the first event after the load. 


If output is being saved, halting the experiment will show up as a keystroke of '#', 
while going back will show up as a keystroke of '<', 


When the Experiment Gets Interrupted 


When running an experiment, MacLab loads up as many pictures as memory can 
hold (they take up 22K each), or a maximum of 200, whichever is less, and goes 
through the trials as long as it has pictures. When it runs out of pictures it puts up the 
load-time display picture and loads up as many pictures as it can. The algorithm that 
does this is smart in that it does not reload pictures that it already knows about, but only 
new ones. If there is enough memory, MacLab will only interrupt the experiment 
between trials. Ifa trial order file is used, and there is enough memory, MacLab will 
only interrupt the experiment where trial number 0 is specified. By clever placing of 
trial O's, you can make MacLab interrupt at the optimal places for your experiment. 


The experiment might also be interrupted for very short periods of time if, since 
the last load, the output file has swelled to above 3.5 K or experiment has run through 
200 lines of experiment. During these times, the load-time diplay picture is put up. 


SCRIPTS 


Script files allow you to put together one or more experiments and run them one 
after another without having MacLab ask you what to do next every time an 
experiment ends. This facility consists of two menu choices in the Miscellaneous 
menu, "Make Script" and "Run Script." 


Making A Script File 


When you want to make a script, you are first asked for a file name to save the 
script to. Then you are asked, for each experiment, three questions: a) the name of the 
experiment to run, b) the name of the output file to which the subject's responses are to 
be saved, and c) the name of a trial order file that should be used. Once you are done 
entering your information, click in the Cancel button when you are asked for an 
experiment file. 


Running A Script File 


When you choose to run a script file, all you are asked for is the name of the 
script file. Thus, if you are even only running one experiment, it is easier to run a script 
file than to run an experiment, since when you run an experiment you are asked for the 
name of the experiment, the name of an output file, and the name of a trial order file. 


NOTE: If, while running a script, MacLab finds that the output file you have 
indicated is the same file as the output file used when running the previous experiment 
in the script, then the subject's responses are added on to the end of the file (i.e. the file 
is not restarted from scratch). Thus it is possible to run several experiments and 
accumulate all of the responses in the same file. 


CAUTION: If the name of an output file is the same as that of an already existing 
text file (it has to have the type TEXT), the old file will be destroyed (with the 
exception noted above). No cautionary messages are issued. 


Script File Format 


A script file consists of sets of three lines. The first line starts with the characters 
"E:" followed by a space. In the next 4 bytes is the length of the file name that follows. 
The file name is that of an experiment file. It is followed by a carriage return. The 
second line starts with the characters "O:" followed by a space; again, in the next 4 
bytes is the number of characters in the file name that follows. This is the name of an 
output file, and it is followed by a carriage return. Finally, the third line in each set 
starts with the characters "T:" followed by a space, then by 4 bytes that hold the number 
of characters in the file name that follows. This is the trial order file to be used, and it 
is followed by a carriage return. 
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If any of the last two files in each set are not to be used, the length of the file 
name should be set to 0. 
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TECHNICAL DETAILS 


Run-time Timing 


The Macintosh screen is refreshed 60 times a second, or once every 16.7 
milliseconds. This would lead one to believe that MacLab should be able to display 60 
pictures per second. That is not true, however, because it takes more than 17 
milliseconds to do the memory move necessary to display a loaded picture. So MacLab 
can only display 30 pictures per second (a new picture every other screen refresh). 


Since pictures can only be changed 30 times a second, the minimum time for a 
picture to be displayed is 33 milliseconds. The display time can thus be 33 
milliseconds and up, in increments of approximately 17 milliseconds (33, 50, 67, 83, 
100, 117, 133, _). When entering display times, the experiment editor coerces the 
display times you enter to the next higher acceptable value. 


Another detail to consider is that, since it takes almost 17 milliseconds to refresh 
the screen, a picture isn't really displayed all at once, but the top of the picture is seen 
almost 17 milliseconds before the bottom of the picture is drawn in. This is not a 
noticeable effect (one cannot really tell that the picture is being drawn from the top 
down), but might be important for some types of experiments. Thus, when I say that a 
picture with a timed exposure is displayed for 100 milliseconds, that really means that 
every individual point in the picture is displayed for 100 milliseconds, since it takes as 
long to draw a picture as to erase it (erasing it just means drawing the next picture over 
it). The picture in its entirety is on the screen by about 17 less milliseconds, or 83 
milliseconds. 


Timed responses, however, are done a bit differently. The millisecond timer is 
started exactly when the entire picture has been drawn on the screen. When the subject 
responds with a key press or a mouse click the timer is stopped. Thus the recorded 
subject responses are accurate to within a millisecond. The picture, however, might 
remain on the screen for a maximum of two more refresh cycles (or about 33 
milliseconds), at which time it is replaced by the next picture. 


The magnitude of the lower limits of the measurements seems insignificant, since 
there is also a certain time that passes between when the subject decides which key to 
press and the time when that key actually ends its travel downwards and activates a 
switch. For most types of experiments, the errors inherent in timing are insignificant. 
MacLab reaches, or is very close to the limits imposed by the Macintosh's hardware. 


Limits 
The number of lines in an experiment file is limited because of the upper bound 


that the Macintosh puts on the length of TextEdit records. This limit is 32000 
characters. So, since there are 47 characters per experiment line, there is an overall 
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limit of 680 lines in an experiment. The limitation on the number of trials, however, is 
artificial: it was set at 340 because that seemed like a good number (it allows a file to 
contain the maximum number of trials if each had at least one event in it). 


The allocation of screen buffers is such that the maximum allocation is 4.4 


Megabytes. So on a Macintosh with 6 Megabytes of memory MacLab would not try to 
allocate more screen buffers than on a Mac with 5 Megabytes of memory. 
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